Skip to content

fix: refuse the handover when the approach never moved - #78

Merged
cao-xiao-hao merged 2 commits into
mainfrom
fix/refuse-handover-when-the-approach-never-moved
Oct 30, 2026
Merged

cao-xiao-hao merged 2 commits into
mainfrom
fix/refuse-handover-when-the-approach-never-moved

Conversation

@cao-xiao-hao

@cao-xiao-hao cao-xiao-hao commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Summary

A force-carrying approach that stops without ever having moved from where it started was reported as stalled=True and handed over to the pure-torque hold. That is not contact: at a 2 N setpoint the approach budget is 0.18 N·m, below the 1.8–2.0 N breakaway measured on the bench, so the jaws never leave static friction. The hold then applies 0.20 N·m with kp = kd = 0; over a free stroke that torque is the only thing acting on the jaw and it accelerates until the runaway watch fires — the "fast close" seen after a release-and-regrasp.

The stall verdict now compares the stopped pose with the pose the approach began at.

Changes

  • MotionConfig.no_bite_mm (default 0.5): how close to the approach's start pose counts as "never moved". 0.5 mm sits under the bench's ~0.0103 rad (≈0.76 mm) stick-slip dead band, so a jaw that broke free and then stalled is still read as contact.
  • MoveResult.no_bite / GraspResult.no_bite: set when the force-carrying approach stopped inside that threshold. stalled and reached are both False on this path.
  • grasp() now checks no_bite before the generic "neither reached nor stalled" branch: it releases in place, sends no hold frame, and returns ok=False, no_bite=True, cycles=0.
  • The stall log line separates the two cases: a warning naming the budget and the start pose for the refusal, the existing info line for a real stall.
  • tests/fake_can.py: FakeMotor(breakaway_tau_nm=...) — below that torque the jaw does not move unless it is already moving, so the refusal is reproducible in simulation.
  • tests/test_actions.py: TestTheApproachRefusesToHandOverWithoutBite — a setpoint below the breakaway is refused (no hold frame, last frame kp == 0.0), a setpoint above it still grasps, and a part sitting at the start pose is refused too (the documented trade-off).
  • README.md / README.zh-CN.md: the new field on both result types, a results-section bullet for ok=False, no_bite=True, the refusal in the grasp() row, and no_bite_mm in the config table.

Testing

$ python3 -m pytest -q
...................................................................... [ 14%]
........................................... [ 23%]
...................................................................... [ 38%]
.................................................................. [ 52%]
........................................................................ [ 67%]
............................................................ [ 80%]
.................................................................. [ 93%]
.................ssssssssssss                                            [100%]
464 passed, 12 skipped, 57 subtests passed in 10.06s

Issues

No tracking issue — this reproduces the bench report of a fast close after release-and-regrasp on 2026-10-30.

A force-carrying approach that stops within `no_bite_mm` (0.5 mm) of where
it started was being reported as `stalled=True` and handed over to the
pure-torque hold. That is not contact: at 2 N the approach budget is
0.18 N*m, below the measured 1.8-2.0 N breakaway, so the jaws never leave
static friction. The hold then applies 0.20 N*m with no position or
velocity term, and across a free stroke that torque accelerates the jaws
into the runaway watch -- the "fast close" seen on the bench.

The stall verdict now compares the stopped pose with the pose the approach
began at. Inside `no_bite_mm` the move is flagged `no_bite` instead of
`stalled`: `grasp()` releases in place, sends no hold frame and returns
`ok=False, no_bite=True, cycles=0`. Real contact delta above the threshold
is unchanged, as is the empty-jaw `reached` path.

The fake motor gained `breakaway_tau_nm` so the regression is reproducible
in simulation.

@X-F-R X-F-R left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cross-checked against the mirrored C++ PR (#59); the law, the threshold and the hand-over ordering match. I ran the suite locally (476 passed) — no blocking issues. A few points, roughly by importance:

1. The regression test cannot reproduce the runaway it is named after (tests/test_actions.py:1895)

BREAKAWAY_NM = 0.22 is above the 2 N hold torque (0.20 Nm), so pre-fix the hold could not move the jaw either: the old code returns ok=True, stalled=True, not a powered stroke. The test does fail pre-fix, but it only proves the refusal — not that the refusal prevents the 19 mm walk.

Putting the breakaway inside the measured 1.8–2.0 N band (e.g. 0.19 Nm) and giving the fake some creep_rad_s_per_nm (a pure-torque hold only moves in the fake with creep — see TestHoldTravelGuard.CREEP) reproduces the real path. I checked against this PR:

  • breakaway_tau_nm=0.19, creep_rad_s_per_nm=5.0, no_bite_mm=0 (simulating pre-fix) → ok=True stalled=True cycles=10, jaws end on the closed stop after the whole 120 mm stroke;
  • the same parameters with the fix → ok=False no_bite=True cycles=0, jaws stay at the start.

2. examples/grasp_test.py — the bench tool behind this report — does not know the new flag

  • _report (:277) does not print no_bite.
  • _hold_problem (:319) reports "the hold phase ended abnormally (err=0)"; no_bite is a clean refusal, not a fault.
  • _judge_empty (:340) says "the closing leg ran out of frames while still travelling" — the opposite of a zero-displacement stop.

Whoever runs this next will be pointed the wrong way. Worth handling no_bite explicitly.

3. The refusal applies at every setpoint — intended?

test_a_workpiece_at_the_start_is_refused_as_well encodes a 20 N grasp failing when the part sits at the start pose. Two real sequences hit that: a part already against the open jaw, and a re-grasp in place after release(abort=True) (which sends no opening move).

The dangerous 0.9x/1.0x gap only exists when the approach budget is within ~10% of the breakaway. At 20 N the budget is 1.8 Nm, ~9x the measured breakaway, so a zero-displacement stop there is almost certainly contact. If the conservative behaviour is deliberate, please call out the re-grasp-after-abort consequence in the docs; otherwise consider gating the refusal on the budget being near the breakaway (e.g. a configurable upper bound).

4. Residual gap: a start within reach_tol of the target bypasses the check entirely

judge_stall (src/litegrip/actions.py:1583) is false when the approach starts within reach_tol of the target, so no_bite can never be set there. With a start 0.05 mm from the closed stop and a budget below the breakaway I measured ok=True, reached=True, no_bite=False, cycles=4 — the hand-over this PR is meant to prevent still happens. It is bounded by hold_runaway_rad, but the README's "the hold is never entered" / "stalled and reached are both False on this path" is too absolute for this window.

5. Smaller items

  • README.md:379 / README.zh-CN.md:327: the no_bite bullet sits under "A fourth combination is a failure"; it is a fifth combination. The C++ PR introduces it as "A fifth one is a refusal" — worth mirroring.
  • LiteGrip.grasp's docstring (src/litegrip/gripper.py:1390) and actions.grasp's docstring still only document released / travel_guard; no_bite appears only in the README.
  • The new branch (src/litegrip/actions.py:884) duplicates the generic "neither reached nor stalled" refusal just below it. Sharing the result construction would keep the two paths from drifting.

Review feedback (X-F-R): the refusal applied at every setpoint, so a part
already against the open jaw — or a re-grasp in place after
release(abort=True), which sends no opening move — was refused even at
20 N, where a zero-displacement stop is contact, not a budget that cannot
break away.

MotionConfig.breakaway_nm (0.2 Nm, the bracket measured on 2026-10-29)
now gates the verdict: only a budget below it turns a zero-displacement
stop into no_bite. Above it the stop stays `stalled` and is held, which is
the setpoint the caller asked for with nothing ahead of the jaws to run
into.

The regression test now reproduces the runaway it is named after: a fake
with breakaway 0.19 Nm and creep, run with no_bite_mm=0 (the pre-fix
behaviour), walks the jaws >10 mm under the hold; the same bench with the
refusal on does not move them at all. examples/grasp_test.py reports
no_bite as the refusal it is instead of "the closing leg ran out of
frames" or "err=0". Both refusal paths share one result constructor, the
grasp docstrings name the new field, and the READMEs call it the fifth
combination, state the gate, and note the reach_tol edge.
@cao-xiao-hao

Copy link
Copy Markdown
Contributor Author

Thanks — all five points are addressed in 40252ee. Details per point:

1. The regression test now reproduces the walk

Agreed, 0.22 was the wrong side of the measured band. TestTheApproachRefusesToHandOverWithoutBite now uses BREAKAWAY_NM = 0.19 plus CREEP = 5.0, exactly as you suggested. The pair is:

  • test_the_old_handover_walks_the_jaws_across_the_whole_free_stroke — no_bite_mm = 0.0 (pre-fix behaviour): stalled=True, no_bite=False, cycles > 0, jaws travel > 10 mm down the stroke;
  • test_the_refusal_stops_that_stroke_before_it_starts — default config: ok=False, no_bite=True, not stalled/reached, cycles == 0, travel < no_bite_mm, no tau_ff != 0 frames, last frame kp == 0.0.

So the pair now demonstrates the refusal preventing the walk, not just the refusal. (Note: in a 0.2 s hold the old path walks ~15 mm here, not the bench's 19 mm — the assertion is > 10 mm, the bench figure is in the comment.)

2. examples/grasp_test.py knows no_bite

  • _report first line now prints ok=... stalled=... no_bite={result.no_bite} runaway_watch=...;
  • _hold_problem returns None when result.no_bite — it is a refusal, not a hold fault;
  • _judge_empty / _judge_loaded early-return [_no_bite_problem(result, motion)], which computes floor_n = motion.breakaway_nm / (N_TO_NM * motion.press_safety) and tells the operator to raise --force above floor_n + 0.1, instead of the "ran out of frames while still travelling" message.

3. The refusal is gated on the budget being near the breakaway

Taken the "gate it" option, since at 20 N a zero-displacement stop is almost certainly contact. New MotionConfig.breakaway_nm = 0.2, and the flag is only set when force_n * N_TO_NM * press_safety < breakaway_nm and the approach moved less than no_bite_mm. Recapping what that means at the edges:

setpoint budget × 0.9 verdict on a zero-displacement stop
2.0 N 0.18 Nm no_bite — under the breakaway, so "not moving" says nothing
2.2 N 0.198 Nm no_bite — the 0.9× gap is exactly what we guard
2.5 N 0.225 Nm stalled — above the breakaway, so contact is the reading
20 N 1.8 Nm stalled → normal hand-over

breakaway_nm = 0.2 is the measured value (0.18 Nm could not move the jaw, 0.20 Nm walked 19 mm). Tests: test_the_setpoint_above_the_breakaway_still_grasps (3 N), test_a_workpiece_at_the_start_is_contact_above_the_breakaway (20 N block at start + 0.001·travel → stalled, ok, cycles > 0) and test_a_workpiece_at_the_start_is_refused_below_the_breakaway (2 N → no_bite, no hold frames). Both READMEs document the gate and the 2.5 N remedy.

4. The reach_tol window is documented rather than extended

Your measurement is right and I chose not to widen the check: with reach_tol = 0.02 rad (~0.9 mm) the residual window is bounded by hold_runaway_rad = 0.05 rad, and extending no_bite past judge_stall would mean re-deriving the stall judgement for a case the guard already contains. Instead the comment above judge_stall and both READMEs now say: a start within reach_tol of the closed stop never reaches the stall judgement, reports reached, and the hold has no free stroke to walk — the "hold is never entered" / "stalled and reached are both False" statements now apply to the wider case, with this window called out as an edge.

5. Smaller items

  • Fifth-combination wording fixed in both READMEs ("A fourth combination is a failure… Then a fifth one is a refusal:"), and the grasp row in the field tables mentions the gate.
  • LiteGrip.grasp and actions.grasp docstrings now document no_bite, including the budget gate and the "refuses the hand-over, drop torque, report failure" contract.
  • The two refusals share _refused_handover(move, force, *, no_bite=False) instead of duplicating the GraspResult construction.

Tests: python3 -m unittest discover -s tests -t tests → Ran 478 tests in 9.736s / OK (skipped=12); python3 -m pytest -q → 466 passed, 12 skipped, 57 subtests passed; markdownlint on both READMEs → 0 issues. CI test is green.

@cao-xiao-hao
cao-xiao-hao merged commit 4ce8482 into main Oct 30, 2026
1 check passed
@cao-xiao-hao
cao-xiao-hao deleted the fix/refuse-handover-when-the-approach-never-moved branch October 30, 2026 08:10
@github-actions

Copy link
Copy Markdown

🎉 This PR is included in version 1.2.1 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

released Shipped in a release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants